[docs] Document project serverReadyAction override in VS Code extension - #1459

Pull request overview

Documents how the Aspire VS Code extension handles serverReadyAction for C#/.NET projects, specifically clarifying that users can override the extension-generated default.

Changes:

• Adds guidance explaining that a generated serverReadyAction can be overridden via launch configuration.
• Adds a JSON example showing how to set a custom serverReadyAction pattern/action.

{
  "debuggers": {
    "project": {
      "serverReadyAction": {
        "action": "openIntegratedBrowser",

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

I left two inline comments: debuggers.project also applies to the .NET AppHost, and the sample pattern truncates IPv6 URLs. The existing Copilot feedback already covers the property path and incomplete launch.json shape.

🤖 Automated docs-accuracy review — ⚠️ changes requested

Phase A source of truth: microsoft/aspire @ release/13.5 (SHA 1d922813c0f9bc14f7d817c817a8ab46b288bb44) — the branch this PR targets.
Claims extracted: 3 non-narrative → 1 verified, 1 contradicted, 1 unverifiable, 0 verified-with-nuance.
Phase B (doc-tester): exercised /get-started/aspire-vscode-extension/ on a local dev server serving this PR — page renders (HTTP 200), 0 critical, 0 warnings.

Headline

The new section documents a debuggers.project.serverReadyAction override that is not implemented on release/13.5. On this branch the extension unconditionally overwrites any user-supplied serverReadyAction for project resources, so the documented override has no effect. The mechanism that makes it work exists on main (guarded by serverReadyAction === undefined), so this doc appears to have landed on the release branch ahead of the code. See the two inline comments for the exact source evidence.

Phase A — Claim verification

Two inline comments are anchored to the affected lines (the contradicted override claim, and the openIntegratedBrowser example that doesn't exist on this branch).

Phase B — Doc-tester results (blind "new user" pass, no source code consulted)

Route exercised: /get-started/aspire-vscode-extension/ (served from a local Astro dev server with this PR's content; navigated via playwright-cli).

✅ Passed checks

• Page compiles and returns HTTP 200; title "Aspire Visual Studio Code extension | Aspire". No MDX/compile errors, no browser console errors.
• The new paragraph renders with correct inline-code formatting (serverReadyAction, launchSettings.json, project.serverReadyAction).
• The new JSON block renders with its title ".vscode/launch.json — override the generated serverReadyAction", correct syntax highlighting, and a working copy button; it is placed logically between the debuggers-keys paragraph and the following env/args paragraph.

🔴 Critical issues

• None (rendering).

⚠️ Warnings

• None.

💡 Recommendations / knowledge gaps (minor, non-blocking)

• The allowed action values aren't enumerated, so a reader can't tell what is valid besides the openIntegratedBrowser shown.
• The relationship between the pattern capture group and the URL the browser opens isn't explained.

Blind-user note: nothing on the rendered page reveals the accuracy problem — it reads as a well-formed, working feature. The mismatch is only detectable by checking the extension source on the target branch (Phase A). This is the intended division of labor between the two phases.

Verdict

REQUEST_CHANGES — one contradicted claim: the documented project.serverReadyAction override does not function on release/13.5 (the user value is silently overwritten by the generated default). Suggested resolution: port the override support (the serverReadyAction === undefined guard in dotnet.ts) to release/13.5, or retarget this documentation to the branch/release where the override actually ships. The "generated default" paragraph (verified) is accurate and can stay.

_{Reviewed head SHA 2e8a9a725e00bc1e43fb1addd00669c0913e5082. Phase A read microsoft/aspire@release/13.5: extension/src/debugger/{languages/dotnet.ts, debuggerExtensions.ts, launchProfiles.ts, test/dotnetDebugger.test.ts}.}

🤖 Automated docs-accuracy review — ⚠️ changes requested (revision 4a97126)

Phase A source of truth: microsoft/aspire @ release/13.5 (SHA e076d8e427cb3afb528dbd605acd74c3aea69f94) — the branch this PR targets. Cross-checked main (SHA 7adcc4c92d9c48d96050096a2c37afb0ee7ba219) only to locate where the underlying fix lives.
Claims: 6 non-narrative → ❌ 1 contradicted · ⚠️ 1 unverifiable · 🟡 2 verified-with-nuance · ✅ 2 verified.
Phase B (doc-tester): exercised /get-started/aspire-vscode-extension/ on a local dev server serving this revision — page renders (HTTP 200), 0 critical, 0 warnings.

Headline (re-review of the updated revision)

Thanks for the update — the new AppHost behavior note is accurate (verified below). However, the core issue from the previous review still stands: on release/13.5 a user-supplied debuggers.project.serverReadyAction is silently overwritten for project resources, so the documented override does not take effect on the branch this PR targets. The fix that makes the override work (and that stops the extension generating a default at all) lives on main (source PR #19200, milestone 13.6), not on release/13.5. See the two inline comments.

Verdict: REQUEST_CHANGES — one contradicted claim (the override) plus an unverifiable action value. Suggested resolution (unchanged): retarget this doc to the release where #19200 ships, or wait until the fix is on release/13.5.

Phase A — Claim verification

Two inline comments are anchored to the affected lines.

Phase B — Doc-tester results (blind "new user" pass, no source consulted)

Route exercised: /get-started/aspire-vscode-extension/ (served from a local Astro dev server with this revision's content).

✅ Passed checks

• Page compiles, returns HTTP 200 (title "Aspire Visual Studio Code extension | Aspire"), 0 browser console errors.
• New paragraph renders with correct inline-code formatting; the :::note[AppHost behavior] renders as a callout with the precedence sentence.
• The new JSON block renders with title ".vscode/launch.json — override debuggers.project.serverReadyAction", correct highlighting and a working copy button, placed logically between the debuggers-keys paragraph and the following env/args paragraph.

🔴 Critical issues

• None (rendering).

⚠️ Warnings

• None (rendering).

💡 Recommendations / knowledge gaps (minor, non-blocking)

• The allowed action values aren't enumerated, so a reader can't tell what is valid besides the openIntegratedBrowser shown.
• The relationship between the pattern capture group and the URL the browser opens isn't explained.

Blind-user note: nothing on the rendered page reveals the accuracy problem — it reads as a well-formed, working feature. The mismatch is only detectable by checking the extension source on the target branch (Phase A). This is the intended division of labor between the two phases.

_{Reviewed head SHA 4a97126da745ea67ffa5ac191beb37db21b2a372. Phase A read microsoft/aspire@release/13.5 extension/src/debugger/{languages/dotnet.ts, debuggerExtensions.ts, launchProfiles.ts}; main consulted only to locate the #19200 fix.}

I do not have anything to add beyond the existing review threads.